TextureStudio, shareware texture renderer for the Amiga. Copyright (C) 1995 Andy Dean, Graham Dean. Welcome to TextureStudio, shareware texture renderer for the Amiga. This document applies to version 1.0.x, written on 10th May 1995, Copyright (C) 1995 Graham Dean, Andy Dean. Introduction ************ This chapter gives a brief introduction into the features offered by the program. Copyright and Disclaimer ======================== No guarantee of any kind is given that the programs described in this document are 100% reliable. You are using this material at your own risk. The authors *can not* be made responsible for any damage which is caused by using these programs. The unregistered package is freeware, but still copyright by Graham Dean and Andy Dean. This means that you can copy it freely as long as you don't ask for a more than nominal copying fee. The registered version of the program and its associated keyfile *may not* be freely distributed. Permission is granted to include the unregistered package in Public-Domain collections, especially in the excellent Fred Fish Amiga Disk Library (including CD ROM versions of it). The distribution file may be uploaded to Bulletin Board Systems or FTP servers. If you want to distribute this program you must use the original unmodified distribution archive. This program (or parts of it) may not be included or used in commercial programs unless by written permission from the authors. The textures Blades.itx, Radar.itx, Target.itx and WarningStripes.itx are freely distributable and may be used in any pictures, renders or programs without permission from the authors. Installer and Installer project icon (c) Copyright 1991-93 Commodore-Amiga, Inc. All Rights Reserved. Reproduced and distributed under license from Commodore. INSTALLER SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO WARRANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY OR RESPONSIBILITY IS ASSUMED. Imagine and its texture format is (c) Copyright 1994 Impulse Inc. Mpls, MN 55444. Machine requirements ==================== TextureStudio requires the following system to run: * Workbench 2.04 or above. * A machine equipped with a 68020 or greater and an FPU (floating point unit) * Around half a megabyte of free memory. Brief description ================= TextureStudio supports the loading of texture modules in Imagine3 format. The parameters of the texture can quickly and easily be adjusted by means of slider gadgets or by typing in the numbers. The texture can then be mapped onto a plane, cylinder or sphere and rendered to a preview screen and/or as a 24-bit image to disk. Many aspects of the texture and render can be altered including axis position/alignment/size, lighting settings, object colours, object size etc. TextureStudio allows the user to quickly render the texture and explore the effects of changing various parameters without the need to ray-trace a new image each time something altered. TextureStudio can render images to disk in ILBM-IFF24, JPEG or Targa format. This allows high quality images to be rendered and loaded into other programs. 24-bit images of any size can be rendered, regardless of memory available. Some example textures are included in the distribution but Imagine3 is required to be able to use it's textures. List of features ================ * Supports Imagine3 texture format. * Control of features via ARexx port. * Render unlimited number of textures simultaneously. * Render to HAM screen and 24-bit images on all Amigas. * Render 24-bit images of any size onto disk in IFF-ILBM24, JPEG or Targa format, regardless of memory available. * Saving of HAM preview screen to disk. * Support for colour, filter and bump type textures. * Easy adjustment of parameters by means of slider gadgets. * Map textures onto a plane, cylinder or sphere. * Control of light colour, distance, position, backlighting and intensity. * Adjustment of axis alignment, size and position. * Control of object size, visible width and image aspect ratio. * Multiple pass render to allow quick preview of image whilst it renders. * 5 levels of anti-aliasing available. * Preview colours with colourbox window. * Alter render screens width, height and screenmode. * Control of all main functions from floating windows. * Optimised code for 68881 and 68882 FPU's for maximum speed. * Render plane, cylinder or sphere without any texture to quickly set up lighting etc. * Loading and saving of textures settings, parameters and axis positions. * Render preferences to alters speed and accuracy of render. * Configure window positions, screenmode, default settings and then save preferences to disk. * Runs on all Amigas with Workbench2.04 or above and an FPU (floating point unit). * Standard Workbench2 interface. * Uses public screen. Shareware version ================= The shareware version is limited in that only the first 8 parameters of the texture can be adjusted. No other features have been removed. The full version allows all 16 parameters to be altered. For details on how to register, see How to register. Starting TextureStudio ====================== TextureStudio can be started from either the Workbench or CLI. From the Workbench it is simply a case of double-clicking on the icon. To start TextureStudio from the CLI, simply type: run TextureStudio The tooltypes can also be typed in on the CLI. For example run TextureStudio "PUBSCREEN=TS" "PREFSFILE=Prefs/SmallScreen.prefs" would start the program on a public screen named `TS' and the preferences would be taken from the file `Prefs/SmallScreen.prefs'. See Tooltypes, for a list of available tooltypes. Quick start *********** This tutorial is designed to quick introduction to some of TextureStudio's features. The Imagine3 textures are required later in the tutorial. Firstly, we shall demonstrate TextureStudio's ability to render a texture onto a plane. Load TextureStudio if you haven't already. Open the `Object' window by selecting `Show object' in the `Windows' menu. Select the `Object' to be a `Plane'. Make sure `Allow transparent object', `Calculate surface normals', `Full light calculations' and `Multiple pass render' are all set in the `Prefs' menu. Open the `Colours' window and select the `Object colour' to be light grey (150,150,150). You can see the actual colour being edited by opening the `Colour box' window from the `Windows' menu. Now we are ready to render the object, at the moment there are no textures open, but that's OK, we'll just render the plane with no textures mapped onto it. Click on `Render' in the `Infobar' window. A grey plane should be rendered fairly quickly to a HAM view screen (HAM8 on AGA machines, HAM6 otherwise). Click the right mouse button to bring TextureStudio to the front. The image should have been rendered in a series of passes, allowing you to see a general view of the image, more quickly than if it was rendered line by line sequentially, this is set by the `Multiple pass render' preference. You may have also noticed that the plane had some shading on it, this is due to the light source and many aspects of the lighting can be altered, we shall discuss this later in the tutorial. Any time you want to stop the render, just press the right mouse button. OK, so we have now seen how TextureStudio can render to a flat plane, but it's not very exciting without a texture mapped on to it. Open the `Texture' window, if it is not already open. Now select `Open texture...' from the `Project' menu, or `Open...' from the `Texture' window to load in a texture module. Select `Radar.itx' which is distributed with this package. Click on `OK' to load it in. Now you should see that `Radar' has appeared in the listview in the `Texture' window. This list shows the all the textures that are currently open, it is possible to load as many as you like with TextureStudio. You should also see that in the `Parameters' window, the parameters for the current texture are displayed, for the moment we shall use the default parameters. Now click on `Render' again, you should now see the image of the `Radar' texture being mapped onto a plane. We can adjust the settings of the texture using the parameters window. If you are running TextureStudio on a screen of heigth 256 pixels or more, you can display the full parameters window and so make sure the `Small parameters window' preference is turned off. If TextureStudio's screen height is less than 256 (ie screen size of 640 x 200) then you can only fit the small parameters window on the screen (the small parameters window doesn't have slider gadgets). The advantage of using the full parameters window is that the parameters can quickly be adjusted by the slider gadgets and there is no need to type in the numbers. Let's adjust some of the parameters for the `Radar' texture. Change the `Sweep angle' parameter to about 45 degrees. Now change the `Radar colour' to be bright red (255,0,0), again, if you have the colourbox window open, you will be able to see actual the colour being adjusted. Now click on `Render' again to see the changes made. This is one of TextureStudio's most useful features, the ability to change one or more parameters, and then quickly re-render the texture to see the changes made. This makes the process of getting the texture parameters just right much easier than having to ray-trace the scene many times. You may have noticed that the new image was rendered over the old image, this can be turned off by the `Use fresh render screen' preference. Now let's try layering 2 textures together. Open the `WarningStripes' texture supplied with this package. It should now appear at the bottom of the list in the `Texture' window. Textures at the bottom of the list have the highest priority and so will appear on top of the textures in the render scene. The `WarningStripes' texture should also be selected in the list, you can change which texture you want to alter by clicking in the list to select the texture. Try clicking on the `Radar' texture in the list and then clicking back on the `WarningStripes' texture, notice how the parameters window changes depending on the currently selected texture. Now click on `Render' again. You should be able to see how the `WarningStripes' texture has been layered on top of the `Radar' texture. Move the `WarningStripes' texture up in the texture list by selecting the `WarningStripes' texture and then clicking on `Up' in the `Texture' window. The `Radar' texture should now be at the bottom of the list and so have the greatest priority. Click on `Render' to see the changes. The `WarningStripes' texture is now behind the `Radar' texture. TextureStudio can also map textures onto a cylinder or sphere, we shall now demostrate mapping the `GasGiant' texture (supplied with Imagine3) onto a sphere. Close the `WarningStripes' and `Radar' textures by selecting them and then clicking on `Close' in the `Texture' window. Now load in the `GasGiant' texture. Change the current object to a sphere by selecting the `Sphere' in the `Object' window. Click on `Render' again. You should see an image which looks something like a planet. Now let's try altering the textures axis. Open the `Axis' window. Make sure `View' is set to `Front' and `Edit' is set to `Alignment' in the `Axis' window. Let's rotate the axis so that the texture is on a slant. Change the Y-alignment to be about 30 degrees by typing in the number or using the slider gadget. Now render the scene again. You should be able to see how the textures alignment has changed. Now let's look at the lighting options. Open the `Light' window. Move the light poition to the bottom right, do this by either clicking on the bottom left of the box (on the left of the `Light' window) or by clicking on the `Position' cycle gadget. Now re-render the scene to see the changes made. Change the `Backlight' setting to be 0% and re-render. The backlight setting sets the ambient light, and so setting it to 0% puts areas away from the light source in complete shadow. Set the `Backlight' to 25% and re-render to see the difference. You should now have an image that looks like a fairly convincing planet. Let's save the render screen to disk, so we can view it later or load it in to other programs. Select `Save...' from the `Infobar' window, choose a filename (e.g. "GasGiantPlanet.ilbm") and click on OK. Now suppose we wanted to render this image again later, or just make a few changes, it would be a pain to have to load in the texture again and set up the object, axis and lighting as we have it now. TextureStudio allows you to save all the current texture settings to disk so you can easily load them back again another time. Select `Save texture settings...' from the `Texture' menu, choose a filename (e.g. "Planet.GasGiant") and click on OK. Anytime you want to re-render the scene just load the settings back in, but you will have to make sure that the `GasGiant.itx' texture file is in your current texture directory or else it won't be able to load the file, since TextureStudio does not save the full filename, just the texture name. Another one of TextureStudio's useful features is to be able to render a texture image as a 24-bit image file for use with other programs. Let's try and render a texture as an IFF-ILBM24 file. Close the `GasGiant' texture now. Open the `Agate' texture supplied with Imagine3. Set the current object to be a plane, turn the `Full light calculations' preference off, this removes any highlights due to the light source. Select `IFF-ILBM24' as the `Render file format' from the `Prefs' menu. Next, bring up the render options window by clicking on `Options...' in the `Infobar' window. Click on `Render to file' and choose a filename (e.g. "Ram:TestRender.ilbm"). Change the size of the render if you like, the default is 160 x 128 which is quarter of a low res PAL screen. You can use the screen mode requester to set the screen and size by clicking on `Choose...' level with the `Render to screen' gadget. Now click on `Render', it may take a while to render the image but you can abort it by pressing the right mouse button if you like. Notice that the `Multiple pass render' preference has no affect when rendering to a file. Once TextureStudio has finished, it will have created a 24-bit IFF file. This can then be loaded into other programs that support 24-bit image files (e.g. ImageStudio, see ImageStudio). Well that's the end of the tutorial, I hope it has given you an insight into TextureStudio's features. There are many other features that have not been covered in this tutorial but hopefully you will be able to pick them up fairly easily. Have fun! Menu options ************ Description of all menu items. Project ======= Open texture ------------ Keyboard shortcut - `Amiga - O' This is how the user loads in a texture module from disk. A file requester will appear prompting the user to select a texture file. If the file is not a valid Imagine3 texture file, an error will be displayed. When the texture module has been loaded, it will appear in the `Texture' window. Loading a texture resets the parameters and axis settings. Close texture ------------- Keyboard shortcut - `Amiga - C' This closes and removes the currently selected texture. If all the textures are closed, TextureStudio will render a plane, cylinder or sphere with no texture mapped onto it. Render ------ Keyboard shortcut - `Amiga - R' This renders the textures to a HAM screen and/or a 24-bit image file. If `Render to screen' is selected in the `Options' window, a HAM screen is opened a brought to the front. TextureStudio will then render the textures to the HAM viewer screen line by line. The render operation can be aborted by pressing `Esc' or the right mouse button. If `Render to file' is selected in the `Options' window, a file is opened and the image is rendered in 24-bits to the file. Since TextureStudio renders to image line by line, very little memory is required when only rendering to a file, regardless of the image size. Note: when rendering to a file, the `Multiple pass render' preference is ignored and the image is render from top to bottom in one pass. It is possible to render to the screen and file simultaneously. See Render options. Screen mode ----------- This opens a screen mode requester to allow the user to change the screen mode, width, height and number of colours of TextureStudio's main screen. The screen mode used on startup can be saved with the `Save prefs' menu item in the `Prefs menu', See Save prefs. About ----- Keyboard shortcut - `Amiga - ?' This opens the about window which displays the current version and registered user name. Quit ---- Keyboard shortcut - `Amiga - Q' This closes all currently open textures and quits TextureStudio. Texture ======= Load texture settings --------------------- Keyboard shortcut - `Amiga - D' This loads in a TextureStudio settings format file. Loading in a settings file may alter currently loaded textures, axis settings, object settings, lighting settings, colours and view settings. Settings files may contain any number of textures (including zero), the textures are then attempted to be opened from the user's current texture directory. If there are currently some open textures, then a requester will appear asking the user whether they want to wipe the existing textures or layer the new textures on top of the existing ones. Save texture settings --------------------- Keyboard shortcut - `Amiga - F' This saves out a TextureStudio settings file with information about the current settings of: all open textures, parameters, axis, object, lighting, colours and view settings. A settings file may contain information about any number of textures (including zero). Settings files are particularly useful for saving out all the current information needed to reproduce the exact same effect another time. Settings files are in ASCII text format. Load axis positions ------------------- Keyboard shortcut - `Amiga - G' Loads in a TextureStudio axis file. The axis file contains the settings of the axis alignment, size and position. Save axis positions ------------------- Keyboard shortcut - `Amiga - H' Saves out current textures axis alignment, size and position in ASCII text format. Load parameters --------------- Keyboard shortcut - `Amiga - J' Loads in 16 parameters from a TextureStudio parameters file. Note: TextureStudio does not check to see whether the current texture is the same texture used to save out the parameters file. Save parameters --------------- Keyboard shortcut - `Amiga - K' Saves out the 16 parameters of the currently selected texture. Note: Only the parameters of one texture are saved. Windows ======= Show axis --------- Keyboard shortcut - `Amiga - 1' This opens or closes the axis window. See Axis window. Show colourbox -------------- Keyboard shortcut - `Amiga - 2' This opens or closes the colourbox window. See Colourbox window. Show colours ------------ Keyboard shortcut - `Amiga - 3' This opens or closes the colours window. See Colours window. Show light ---------- Keyboard shortcut - `Amiga - 4' This opens or closes the light window. See Light window. Show object ----------- Keyboard shortcut - `Amiga - 5' This opens or closes the object window. See Object window. Show parameters --------------- Keyboard shortcut - `Amiga - 6' This opens or closes the parameters window. See Parameters window. Show texture ------------ Keyboard shortcut - `Amiga - 7' This opens or closes the texture window. See Texture window. Show view --------- Keyboard shortcut - `Amiga - 8' This opens or closes the view window. See View window. Prefs ===== Beep when finished ------------------ If this is on, when TextureStudio has finished rendering to the screen, it will flash the screen and beep, to alert the user it has finished. Since this could potentially get very annoying, it can be turned off. Flush textures on open ---------------------- If this option is off, whenever a texture is opened from disk, it will be added to the bottom of the texture list and all existing textures will remain open. If this option is turned on, when opening a texture, all existing textures will be flushed out (closed). Multiple pass render -------------------- If this option is turned on, when rendering to the screen, the image will be built up in 3 passes. The first pass renders every 4th line, the second pass renders every 4th line and the third pass renders the remaining lines. The idea of this option is that a general picture of the texture can be seen much quicker than rendering line by line. If this option is turned off, the lines of the image will be rendered sequentially. Small parameters window ----------------------- If this option is turned on, the parameters window used will only contain one number gadget and text field for each parameter. If this option is turned off, the parameters window used will contain slider gadgets to allow quick and easy adjustment of the parameters. This window will not fit on a 200 height or less screen and so the small parameters window will have to be used. Use fresh render screen ----------------------- If this option is turned on, the image will be rendered to a blank screen each time. If this option is turned off, the image will be rendered on top of the existing image (if it exists) and so it is easy to see any changes made since the last render. Allow transparent object ------------------------ If this option is turned off, the filter aspect of the texture and object is ignored and so the object is totally opaque. If this options is turned on, objects can be transparent and filter through light. The option slightly increases render time. Calculate surface normals ------------------------- If this option is turned off, the object will appear totally flat and no shading due to the object shape, lighting or bump texture will show up. Turning this option off is only really suitable when rendering to a plane and using a non-bumpy texture. If this options is turned on, all object shape, lighting and bump textures affect the shading as expected. This option slightly increases render time. Full light calculations ----------------------- If this option is turned off, the object shading due to the light source is slightly reduced and the distance of the light source from the centre of the object is ignored. If this option is turned on, all the object shading from the light source is present. You may wish to turn this option off if you want to render a texture to a flat plane for use as a picture in another program, this will eliminate any shading on the image and give a true representation of the texture alone. See Light window. This option slightly increases render time. Anti-aliasing ------------- Anti-aliasing is a process where the colours in the rendered image are smoothed to reduce the `jagged' affect of the pixels. The higher the anti-aliasing setting, the less noticable the individual pixels are. Anti-aliasing greatly increases render time, the table below shows the times taken to render relative to an anti-aliasing of none. *Anti-aliasing setting Time taken to render* None 1 Low 4 Medium 9 High 16 Very high 25 For most situations, a setting of none is sufficient and anti-aliasing is only really recommended for the final render. For a demostration of anti-aliasing, render the Radar texture to a plane firstly with no anti-aliasing and then with anti-aliasing set to low. Notice the difference with areas of large contrast. Render file format ------------------ This option sets the file format of the image file when `Render to file' is selected in the `Render options' requester, See Render options. If IFF-ILBM24 is selected, the image file is saved in 24 bits as a standard Amiga compressed IFF-ILBM picture. If JPEG is selected, the image file is saved in 24 bits as a JPEG compessed file. JPEG uses `lossy' compression which offers excellent compression ratios (very small files) but there is some loss in quality. The quality of the image saved can be set with the `JPEG options' window, see JPEG options. If Targa is selected, the image is saved as an uncompressed 24-bit Targa (Truevision) file. JPEG options ------------ This window alters the settings when saving out in JPEG format. The `Quality' setting alters the level of compression used in the file, a high value (85 or more) will save out a good quality image but with a relatively large file size. A small quality setting (50 or less) will give a very small file but with significant loss in quality. Note: A quality setting of 25 or less may cause problems with some JPEG readers. Save prefs ---------- This option saves out the current settings and preferences to a prefs file on disk. The prefs filename is set by the `PREFSFILE' tooltype, see Tooltypes. TextureStudio saves out the following details in the prefs file: * Windows positions and whether they are opened or closed. * Current lighting settings. * Current object settings. * Current view settings. * Current render options. * Colours of background, light, object colour and object filter. * TextureStudio's current screen mode, width and height. * All items in the `Prefs' menu. * Current paths for textures, settings, axis, parameters, renders and render screens. After saving the prefs, when loading TextureStudio again, all these details will be used as defaults. Floating windows **************** Notes. All windows can be opened or closed by selecting the relevant items in the `Windows' menu, see Windows. The position and status of all the windows can be saved by selecting `Save prefs' in the `Prefs' menu. Axis window =========== The axis window allows the user to alter the axis alignment, size and position for the currently selected texture. The window visually shows the current axis settings in the box on the left, the viewpoint of which is set by the `View' cycle gadget. The `View' cycle gadget alters direction from which the axis are viewed from. Viewing the axis from the front shows the x-axis horizontally, the z-axis vertically and the y-axis out of the screen, when the axis have not been rotated. The `Edit' cycle gadget adjusts the function of the slider gadgets below. When `Alignment' is selected, the slider gadgets adjust the rotation about the x,y and z axis. When `Size' is selected, the user can alter the length of the x,y and z axis and when `Position' is selected, the slider gadgets adjust the offset of the base of the axis from the central position. As the slider gadgets are moved, the axis are redrawn in real time to give a representation of the changes made. The exact settings of the axis can be altered by typing the numbers into the number gadgets. Each texture may have its own axis settings. Colourbox window ================ The colourbox window contains a square in which the current colour the user is editing is displayed. The current colour can either be from the colour window or a parameter of the current texture. The colourbox window also shows the red, green and blue values for the colour. The colour is displayed by setting the palette of TextureStudio's current screen. If TextureStudio is being run on a 4-colour screen, then the usual blue highlight colour will be altered. To set this back to it's original colour, click on a parameter which does not affect a colour value. Colours window ============== The colours window allows the user to alter the current object colour, object filter, background colour and light colour. The cycle gadget adjusts which colour is currently being edited. The three slider gadgets allow the red, green and blue components of the colour to be altered between 0 and 255. The background colour alters the colour seen `behind' a cylinder or sphere. If the current object is a plane, the background colour cannot be seen and has no affect unless the object has some transparency (see object filter below). The light colour affects the colour of the light source. Setting it to 255,255,255 (pure white) gives a natural representation of colours of the texture. The actual intensity of the light can be altered in the `light' window, see Light window. The object colour affects the base colour of the object. With some textures, the base colour can be seen through the texture pattern, other textures are totally opaque and so the object's base colour cannot be seen. The object filter adjusts the light the object filters through. Setting this to 0,0,0 gives a totally opaque object, setting it to 128,128,128 gives the appearance of slightly transparent object. Note that if the current object is a cylinder or sphere, the `other side' of the object cannot be seen through the front half as you would expect. This is something that may be fixed in the future, see Future additions. Infobar window ============== The infobar consists of a row of buttons to control aspects of the render screen, some text to display the size of the render screen currently open, a `fuel gauge' to indicate the progress of a task and an abort button to stop a task mid-way through. The `Render' button starts rendering the texture(s) to the HAM screen, see Render. The `View' button views the HAM render screen, if it is already open. Pressing the right mouse button sends the sceen to the back again. The `Save' button saves the current HAM render screen to disk as a HAM IFF-ILBM picture file. When clicking on the button, a file requester will appear requesting the user to select a file to save to. The `Close' button closes the current render screen, if it is open. The `Options' button brings up the render options window, see Render options. Light window ============ The light window adjusts the aspects of the light source used to illuminated the scene. The box to the left of the window shows the light source (represented by a circle) relative to the centre of the object (represented by a cross). The bounds of the box represent the bounds of the image as viewed from the front. For example if the light source if placed in the top left of the box, the scene will be lit from a light source in the top left corner of the image. The position of the light can be altered by clicking in the box to the left of the window or by clicking on the `Position' cycle gadget. The `Position' cycle gadget has nine preset positions for the light source to be in. The `Intensity' slider gadget alters to intensity of the light in percentage of the lights colour, See Colours window. Setting this to be 100% gives the actual light colour. A setting of 50% would give a light source half as bright. A setting of 200% gives an `over bright' light source and will cause large highlights on the object, this gives the effect of a very bright spotlight. The `Backlight' slider adjusts the backlighting or ambient light. A setting of 0% gives an object lit from one light source with total darkness in areas facing away from the light source. A setting of 50% gives the impression of some ambient light in all directions around the object, this will eliminate very dark shadows in areas that are not lit by the main light source. The `Distance' gadget alters the distance of the light source from the centre of the object in the y-axis (depth). This setting is ignored if the preference `Full light calculations' is off. For example if you are rendering to a plane and the distance is set at around 20, there will be a very defined highlight on the plane since the light is very close to the object. If the light is moved to a distance of 200 or more, the highlight will be barely visible. The `Full light calculations' checkbox gadget alters the accuracy at which the lighting is calculated. If the gadget is checked, the lighting is calculated as expected and the light distance affects the image. If the gadget is unchecked, the light distance is ignored and the affect on the image is similar to having the light source a very long distance away. This option was added to improve the speed of rendering, since if the gadget is unchecked, the render speed is slightly increased. See Full light calculations. Object window ============= The `Object' cycle gadget alters which type of geometrical shape the texture is mapped onto. If `Plane' is selected, the texture is mapped onto an infinitely big plane in the x and z directions, it is flat in the y direction (depth). If `Cylinder' is selected, the texture is mapped onto a vertical cylinder with circular cross section in the x and y directions. If `Sphere' is selected, the texture is mapped onto a sphere, with the radius being set with the gadget below. The `Radius' gadget sets the radius of the object if `Cylinder' or `Sphere' is selected. If `Plane' is selected, the radius is ignored. Parameters window ================= The parameters window allows the user to adjust the 16 number parameters associated with the currently selected texture. There are 2 parameter windows available, the small parameters window only allows the user to type the numbers directly in, it is designed for a small screen. The larger parameters window has slider gadgets to allow easier adjustment of the numbers, it is designed for a bigger screen (interlaced). The type of parameters window can be toggled by the `Small parameters window' preference, see Small parameters window. The minimum and maximum values for the slider gadgets in the larger parameters window are, by default, -10 and 245 respectively. If the text for the parameter has limits in brackets, (e.g. "Slope adjust (-1..1)") then these are used for the limits. Texture window ============== The texture window displays all the currently open textures. The textures are ordered so that the texture at the bottom of the list has highest priority and so is `on top' when being mapped onto the object (consistent with Imagine3's method). The `Open' button opens a texture module from disk and adds it to the list, see Open texture. The `Close' button closes the currently selected texture and removes it from the list, see Close texture. The `Up' button moves the currently selected texture up in the list and so gives it a lower priority. The `Down' button moves the currently selected texture down in the list and so gives it a higher priority. View window =========== This window adjusts how much of the `world' can be seen and the aspect ratio. The `Visible width' gadget adjust the width of the `window' in which you see the `world' through. For example, if you are rendering a sphere of radius 50, and the visible width is set to 100, the left and right edges of the sphere will just touch the edges of the render screen. The positions of the top and bottom will depend on the aspect ratio. The `X/Y aspect' gadget sets the X:Y ratio for the rendered image. For example if you are rendering to a square screen (128 x 128), then the X/Y aspect ratio is 128/128 = 1. However, most common screen sizes are not square, for example a lores PAL screen is 320 x 256, therefore for a sphere to look spherical and not `stretched', the X/Y aspect ratio must be set to 320/256 = 1.25. For a NTSC screen mode, the aspect ratio will be 320/200 = 1.6. Render options ============== The render options window allows the user to alter the render screen width and height, the render image file name and whether to render to the screen and/or a 24-bit image file. The `Render to file' checkbox alters whether TextureStudio writes to a 24-bit image file. If it is checked, the image will be saved out line by line to a file decided by the filename in the text gadget. Clicking on `Choose' will bring up a file requester to make choosing a file easier. When this option is selected, the `Multiple pass render' preference is ignored, see Multiple pass render. The `Render to screen' checkbox alters whether the current texture(s) should be rendered to a HAM render screen. The corresponding `Choose' button chooses the render screen mode. The `Width' and `Height' number gadgets alter the width and height of the image to be rendered. Note: The image width and height can also be set from the screen `Choose' requester. ARexx ***** This chapter gives information about the program's interface to the ARexx programming language. Introduction to ARexx ===================== ARexx is the script language that is distributed with all Amigas sporting Workbench 2.04 and above. It is used on the Amiga for two main tasks: 1. Providing an easy and consistent method of adding macro facilities to programs. 2. To allow ARexx aware programs to communicate with each other. Most users are dissuaded from using ARexx with their programs because of the learning curve involved in (i) learning ARexx and (ii) using the functions provided with each program. With TextureStudio, we have tried to simplify the process of creating an ARexx script by: 1. Providing a ready-made script template which the user can just "fill in the blanks" to produce a fully working program. 2. Providing many commands to perform commonly performed operations. This means the user needs to write less code in ARexx and doesn't need to rely on external utilities and libraries to perform the operations. Typical uses for ARexx in TextureStudio include: * Animation. A number of frames can be rendered, changing one or more parameters each frame. These frames can then be joined together to form an animation. See RadarAnim script. * Cataloguing. A number of textures can be rendered, one after another and the images saved to disk. This provides a quick reference as to what each texture looks like. See RenderTextures script. * Communication. ARexx can be used to link together 2 or more programs. For example, TextureStudio could render a texture and save the image out in 24 bits. An image processing program could then load in the image, reduce it to 32 colours with dithering and save this new image out as a standard IFF-ILBM file for general viewing. Several example files are given with TextureStudio (see Example scripts), which can either be used directly or modified to perform the desired operation. Basic ARexx =========== This section is meant as a beginners guide to using ARexx with TextureStudio. We cannot hope to teach you the ARexx language, although it is only neccessary to the know the very basics to start using ARexx scripts with TextureStudio. It is assumed that the user is familiar with a text editor (for example MEmacs) for editing scripts. For further information on ARexx, we suggest reading Commodore's ARexx user guide supplied with the A4000 or the Workbench2 and 3 upgrade packs. For A600 and A1200 users who don't get this manual, we recommend the "ARexxGuide" AmigaGuide document by Robin Evans which is a shareware document containing extensive information on the ARexx language. The guide can be obtained from all good PD houses. The ARexx programming language is similar to many other programming languages in its structure. Users who have BASIC, C, FORTRAN, Pascal, Modula2 or Oberon experience will notice many similarites. It is not similar to Assember language, Lisp or Prolog. An ARexx program is, in its simplest form, a list of instructions for TextureStudio to perform. Here is a simple ARexx program: /* A simple ARexx program */ REQUEST_MESSAGE TEXT '"Hello world!"' exit This shows some important things about an ARexx program: 1. All ARexx programs *must* start with a comment line. A comment line is a line which starts with the `/*' sequence of characters and ends with the `*/' characters. Anything between these characters is ignored by ARexx. 2. For clarity, all of TextureStudio's commands are shown CAPITALISED, ARexx commands are kept in lower case. REQUEST_MESSAGE is therefore an TextureStudio command that should be performed. 3. The REQUEST_MESSAGE has some `arguments' or `parameters' following it. These tell the REQUEST_MESSAGE command how to behave, in this case they tell the command to pop up greeting message. 4. To stop an ARexx program, use the command `exit'. OK, lets enhance our program a little: /* A better simple ARexx program */ REQUEST_MESSAGE TEXT '"What do you think of\n'||, 'the show so far?"', BUTTONTEXT "Great|Mediocre|Rubbish" exit From this example we learn: 1. To separate a long command line, place a comma `,' as the last character on the line. This tells ARexx to treat the next line as a continuation of the previous. Two line breaks are used in the above example. 2. ARexx loves to evaluate things. If we want to stop ARexx evaluating variables, the variable should be enclosed in single quotes ` ' '. See ARexx problem 1, if little explanation is needed as to the many double and single quotes used above. If we now tell you that the `\n' characters are used represent a newline and the `||' characters glue string together, we should see that: '"What do you think of\n'||'the show so far?"' would be evaluated to: "What do you think of*the show so far?" where `*' represents a newline. The lesson to be learnt here is that whenever you use a string (with or without spaces) it is best to enclose the whole thing in single quotes outside the double quotes to keep the whole thing together. On with the examples. The previous script isn't much use if we can't test for which button the user pressed, so: /* A better simple ARexx program */ options results REQUEST_MESSAGE TEXT '"What do you think of\n'||, 'the show so far?"', BUTTONTEXT "Great|Mediocre|Rubbish" if RESULT == 0 then REQUEST_MESSAGE TEXT '"Sorry, I was trying very hard."' else if RESULT == 2 then REQUEST_MESSAGE TEXT '"It gets better."' else do REQUEST_MESSAGE TEXT '"We like happy users."' REQUEST_MESSAGE TEXT '"Treat yourself to a coffee."' end exit This shows: 1. Normally ARexx ignores the values returned by commands. To allow commands to return values, use "options results"; this is done for you in the blank ARexx script. 2. Unless otherwise specified (see Return values) commands return the results of their operation in a variable called "RESULT". The command REQUEST_MESSAGE returns the value of the button that the user pressed. It is this value that we can test for. 3. The `if' tests are shown above. Note that if you only want to perform one operation as part of the `if', you can just place it after the `then'. If you wish to perform more operations, they must be placed in a `do / end' set. OK, that's about it for the introduction to ARexx. We really suggest now that you look at the example scripts provided with TextureStudio (see Example scripts) to learn more examples. Have fun! Command templates ================= The parameters passed to the ARexx commands closely follow Commodore's style guidelines. The parsing of the arguments follows the standard template format described below. Commands are always of the form: command [options] The command may be something like `OPEN' or `COLOUR_SET' and the options may be filenames, numbers etc... A typical command template may look like: OPEN FILE/A,FLUSH/S The commands and options are not case sensitive, therefore `OPEN', `Open' or `open' can be used to open a file. The options after the command name are separated by commas, and are named (e.g. FILE or FLUSH are option names). After the name, follows an optional modifier (e.g. /A or /S are modifiers) which describes what type of information the option specifies. When using the command, the option names may be ommitted if the parameters for the command are given in the same order as the options in the template, but for clarity it is recommended that the option names be used. The following modifiers are used: No modifier If the option has no modifier, the option is expecting a string. Strings are lines of text with no spaces; to use a string with a space, place the string in double-quotes ("). Multiple strings (/M) Many strings can be specified if an option uses this modifier. Numeric (/N) Numeric options allow both positive and negative integers. Floating point numbers (decimals) are given as strings in TextureStudio. Boolean (/S) Some options can be specified to "switch" that option on. By leaving the option out, the option is switched off. Keyword (/K) A keyword option shows that the option name must be used to set this option. Always (/A) This option must always be included in this command. In practice, it soon becomes very easy to interpret command templates - some examples with explanations are given below: OPEN FILE/A,FLUSH/S The command `OPEN' is used to open a texture module and load it into TextureStudio. OPEN requires a filename (FILE/A is a string, and is always required), and an optional FORCE switch. The following are valid OPEN commands: The following would load in a texture module called `Radar.itx' from the current directory and add it to any other textures that are already open. OPEN "Radar.itx" The following would open a texture called `Target.itx' from a drawer called `Textures' in the current directory. It would also flush out (close) any textures that are already open. OPEN "Textures/Target.itx" FORCE COLOUR_SET COLOUR/A,R/N,G/N,B/N This command is used to set the colour of the background, light, object or object filter. `COLOUR' is a string which must always be supplied, it determines which of the above colours is to be altered. `R/N',`G/N',`B/N' are integer numbers which set the red, green and blue components of the colour respectively. They are optional. The following sets the background colour to be bright red. COLOUR_SET BACKGROUND 255 0 0 The following sets the green component of the light to be 128 (half brightness) COLOUR_SET LIGHT G 128 The following is an error, an incorrect `COLOUR' parameters is used. COLOUR_SET 255 255 255 The following is not an error, but will do nothing. COLOUR_SET OBJECTCOLOUR Return values ============= The return values for the ARexx commands are specified in the same notation as the input parameters, although the types of returned values is more limited than the input parameter types. In order for results to be returned from ARexx commands, it is essential that the line: options results be placed near the start of the ARexx script. Commands may return either strings, numbers or arrays of either. By default, all ARexx commands return their values in a variable called "RESULT". This is fine if the command returns a single number or string. For example, the following call to the FILE_JOIN command (see FILE_JOIN) would return the string "T:Image.ilbm" in the RESULT variable: FILE_JOIN PATHPART "T:" FILEPART "Image.ilbm" If the user wishes to return the result in another variable other than RESULT, they may specify the VAR keyword. For example, the following would perform the same action as above, only putting the result in the varible called "FULLNAME" FILE_JOIN PATHPART "T:" FILEPART "Image.ilbm" VAR FULLNAME Some ARexx commands return multiple values, and these to can be returned in a single variable - each returned value in the variable is seperated with a space. The following returns information about the current image (see LIGHT_GET): LIGHT_GET and RESULT might look something like this: -0.700000 -0.700000 100 0 150.000000 It is possible then to extract the desired information using ARexx's built in parsing routines. A neater way to return multiple values though is through a "stem" variable. Here, a base name for a variable is given and the returned values' names get added to it. It is clearer with an example: LIGHT_GET STEM LIGHT. would return the same information as previously, only it would create the following variables: LIGHT.X_POS = -0.700000 LIGHT.Z_POS = -0.700000 LIGHT.INTENSITY = 100 LIGHT.BACKLIGHT = 0 LIGHT.DISTANCE = 150.000000 Now you can refer easily to the returned values. If an ARexx function returns an array of results, they are named as follows: STEMNAME.RESULTNAME.NUMBER with the variable STEMNAME.RESULTNAME.COUNT holding the number of returned results. This example would display a multi-select file requester and return the selected files. REQUEST_MULTIFILE PATHPART "Textures" PATTERN "#?.itx" STEM MATCHED. which might return the following: MATCHED.FILES.COUNT = 4 MATCHED.FILES.0 = Blades.itx MATCHED.FILES.1 = Radar.itx MATCHED.FILES.2 = Target.itx MATCHED.FILES.3 = WarningStripes.itx Error checking ============== TextureStudio uses the standard ARexx method of returning errors, with a further extension. Whenever a command is executed, a variable called "RC" has its value set by ARexx. If the command executed normally, RC is set to zero. If any failure happened, RC is set to either 5 (warning), 10 (failure) or 20 (serious failure). TextureStudio also sets the value of a further variable called "RC2", which either contains a text description of the reason for failure or a standard AmigaDos error code. A description string is returned in RC2 if a failure occurs within the execution of a command. RC2 will be an AmigaDos error number if there is an error with the command syntax (e.g. mis-spelled command name or missing quotes). If, for example the user was to try and close a render screen that wasn't open, RC and RC2 would be set to the following: RC = 10 RC2 = "RENDERSCREEN_CLOSE, No render screen open." If the close operation were to be performed with the command: COLSE the following values would be set: RC = 10 RC2 = 236 where AmigaDos error 236 represents `not implemented', i.e. unknown command. The default blank script template will convert the most common likely AmigaDos error codes into description strings (see Commodore's AmigaDos manual for a full description of AmigaDos errors). By default, the blank script template turns on automatic error checking. The line: signal on error tells TextureStudio to jump to the ERROR: label whenever a command fails. The blank script then puts up a requester showing the error. The user may wish to turn off the automatic error checking to perform error checking themselves. This is neccessary, for example, if the user wishes to trap the user pressing `Cancel' on a requester (this returns an error). The following checks when the user cancels the file requester: /* Turn off automatic error checking */ signal off error /* Open the requester */ REQUEST_FILE /* Check for the error condition */ if RC ~= 0 then do REQUEST_MESSAGE TEXT '"An error occurred (user\n'||, 'probably pressed Cancel)"' end else do REQUEST_MESSAGE TEXT '"You chose: '||RESULT||'"' end Common ARexx problems ===================== ARexx problem 1 --------------- "I can't use strings with spaces in them." Care must be taken when specifying string paramters when the string contains space characters. Single quotes must be used around double quotes to stop the string from being seen as many different strings. Consider the following example: REQUEST_MESSAGE TEXT "Hello" ARexx would evaluate the string "Hello" and give TextureStudio the following command to execute: REQUEST_MESSAGE TEXT Hello i.e. without the double quotes. In this example, REQUEST_MESSAGE would do as expected. The problems start when strings have spaces in them; consider the following: REQUEST_MESSAGE TEXT "Hello world" ARexx would evaluate the string "Hello world" and give TextureStudio the following command to execute: REQUEST_MESSAGE TEXT Hello world which is not what is desired. The Hello becomes the TEXT value and the world becomes the value of the next parameter (BUTTONTEXT in this case). The result would be a requester with the text of "Hello" and a button called "world". Now we must use the single quotes to stop ARexx from evaluating the string: REQUEST_MESSAGE TEXT '"Hello world"' would send TextureStudio the following command: REQUEST_MESSAGE TEXT "Hello world" which shows that the whole string "Hello world" belongs to the TEXT parameter. ARexx problem 2 --------------- "I can't set the same variable twice with VAR" If you are able to return a value from a command into a given variable name once in a program, but unable to do it again it's probably due to ARexx evaluating your variable the second time it is used. For example, the following won't work: FILE_JOIN FILEPART '"Work:"' '"MyFile"' VAR fullname FILE_JOIN FILEPART '"Work:"' '"MyOtherFile"' VAR fullname because ARexx will evaluate `fullname' in the second FILE_JOIN, i.e. ARexx will see the second FILE_JOIN as: FILE_JOIN FILEPART "Work:" "MyFile" VAR Work:MyFile The solution is to enclose the variable name in single quotes to stop it from being evaluated, i.e. our second FILE_JOIN is written as: FILE_JOIN FILEPART '"Work:"' '"MyOtherFile"' VAR 'fullname' ARexx tips ========== ARexx tip 1 ----------- "Shortening command names" Using the current ARexx command interpreter within TextureStudio, it is possible to specify a shorter version of each ARexx command. For example, `OP' could be used as a synonym for `OPEN' and `CL' is a synonym for `CLOSE'. The following should be noted however: * This behaviour may be removed in a future version of TextureStudio. Therefore we recommend that in ARexx scripts, the full command names should be used. * If the shortened command name is ambiguous, the first matching command will be executed. For example, if the shortened command `REQUEST' is used, `REQUEST_DIR' will be executed. Example scripts =============== The following scripts require TextureStudio to already be running. To run the script, either double click on the script icon from the Workbench, or from the shell, type rx RadarAnim.tsrx for example. RadarAnim script ---------------- Description The user will be asked to select the `Radar.itx' texture, the default directory will be the user's current texture path. The user will then be prompted to select a destination directory where the rendered pictures will be saved to. Finally, the user will be asked to select the number of frames from 10, 25, 50 or 75. TextureStudio will then render the frames of the animation as HAM screens to the destination directory. The images will be rendered to a screen at the back, this can be brought to the front if you wish, to see the image being rendered. The resulting frames can be joined together into an animation using a suitable program. The animation shows a radar scanner scanning through 360 degrees. Known bugs None. RenderTextures script --------------------- Description The user will then be prompted to select some texture modules to render. By shift-clicking on the files, many textures can be selected. The user will then be prompted to give a destination directory for the resulting render screen files created. The script renders each texture in turn and then saves the HAM render screen to the given directory. All the settings e.g. object, light etc. are kept as the current settings. This is particually useful for keeping a record of all the textures and what they look like for quick reference. Known bugs None. RenderTexturesIS script ----------------------- The ARexx script requires ImageStudio, see ImageStudio. Description This scripts is similar to the `RenderTextures' script but requires both TextureStudio and ImageStudio running at the same time. This scripts renders each texture, saves it out as a 24-bit for ImageStudio which then reduces the image down to 32 colour with dithering and then saves the new image as an IFF-ILBM file. See RenderTextures script. Known bugs None. RotatePlanetAnim script ----------------------- Description This script requires the `GasGiant' texture supplied with Imagine3. The script is similar to the `RadarAnim' script but produces an animation which looks similar to a planet (like Jupiter) spinning on its axis. See RadarAnim script. Known bugs None. ARexx commands ============== More detailed information on each of the individual ARexx commands can be found below. AXIS_GET -------- Command AXIS_GET Parameters template None. Return template X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT, X_SIZE,Y_SIZE,Z_SIZE, X_POSITION,Y_POSITION,Z_POSITION Description This command returns the axis settings for the currently selected texture. Parameters None. Returns X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT These variables contain the axis alignment as floating point numbers. X_SIZE,Y_SIZE,Z_SIZE These variables contain the axis size as floating point numbers. X_POSITION,Y_POSITION,Z_POSITION These variables contain the axis position as floating point numbers. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example gets the current axis settings and puts them in a stem called axis. The settings can then be accessed by `axis.x_alignment', `axis.y_alignment' .... AXIS_GET STEM 'axis.' Known bugs None. See AXIS_SET. AXIS_SET -------- Command AXIS_SET Parameters template X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT, X_SIZE,Y_SIZE,Z_SIZE, X_POSITION,Y_POSITION,Z_POSITION Return template None. Description This command sets the axis settings for the currently selected texture. Parameters X_ALIGNMENT,Y_ALIGNMENT,Z_ALIGNMENT These variables contain the axis alignment as floating point numbers. X_SIZE,Y_SIZE,Z_SIZE These variables contain the axis size as floating point numbers. X_POSITION,Y_POSITION,Z_POSITION These variables contain the axis position as floating point numbers. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example sets the axis alignment so that the z-axis is perpendicular to the surface of a vertical plane. AXIS_SET X_ALIGNMENT -90 Y_ALIGNMENT 0 Z_ALIGNMENT 0 Known bugs None. See AXIS_GET. CLOSE ----- Command CLOSE Parameters template NAME,ALL/S Return template None. Description This commands closes one or all of the currently open texures. If no parameters are supplied, only the currently selected texture is closes. Parameters NAME NAME is the name of the texture to be closed. This can be shortened to the first few characters in the name. The NAME string is case insensitve. FLUSH/S If FLUSH is given, all currently open textures are closed. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example closes the currently selected texture. CLOSE The next example closes any textures beginning with `Rad', which could close `Radar', `RadCheks' .... CLOSE "Rad" The following example flushes out all existing textures. CLOSE ALL Known bugs None. COLOUR_GET ---------- Command COLOUR_GET Parameters template COLOUR/A Return template R/N,G/N,B/N Description COLOUR_GET gets the red, green and blue values of the given colour. Parameters COLOUR/A This specifies which colour is to be returned. Valid strings are: BACKGROUND (shortest abbreviation: BACK) LIGHT (shortest abbreviation: LIGHT) OBJECTCOLOUR (shortest abbreviation: OBJECTCOL) OBJECTFILTER (shortest abbreviation: OBJECTFIL) Returns R/N,G/N,B/N These are the red, green and blue componets of the given COLOUR, the numbers are between 0 and 255. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following is an example where the colour of the light source is returned in the `light.' stem. COLOUR_GET LIGHT STEM 'light.' Known bugs None. See COLOUR_SET. See Colours window. COLOUR_SET ---------- Command COLOUR_SET Parameters template COLOUR/A,R/N,G/N,B/N Return template None. Description This command sets the red, green and blue components of the given COLOUR. Parameters COLOUR/A This specifies which colour is to be altered. Valid strings are: BACKGROUND (shortest abbreviation: BACK) LIGHT (shortest abbreviation: LIGHT) OBJECTCOLOUR (shortest abbreviation: OBJECTCOL) OBJECTFILTER (shortest abbreviation: OBJECTFIL) R/N,G/N,B/N These are the red, green and blue componets for the given COLOUR, the numbers should be between 0 and 255. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example sets the colour of the background to be white. COLOUR_SET BACKGROUND 255 255 255 The following example turns the red component of the light source off. COLOUR_SET LIGHT R 0 Known bugs None. See COLOUR_GET. See Colours window. FILE_JOIN --------- Command FILE_JOIN Parameters template PATHPART/A, FILEPART/A Return template FILE Description Joins the path part of a filename to the file part of a filename, returning the full filename. Adds `/' and `:' where appropriate to create a full filename. Parameters PATHPART/A The path (directory) part of the filename to be created. FILEPART/A The file part of the filename to be created. Returns FILE The full filename created from the path and file parts. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following creates the filename "Textures/Radar.itx" from the seperate path and fileparts - the result is put in a pop up requester: FILE_JOIN PATHPART "Textures" FILEPART "Radar.itx" REQUEST_MESSAGE TEXT '"'RESULT'"' The following creates the filename "Ram:Radar.itx" from the seperate path and fileparts (note how the '/' seperater is not needed) - the result is put in a pop up requester: FILE_JOIN PATHPART "Ram:" FILEPART "Radar.itx" REQUEST_MESSAGE TEXT '"'RESULT'"' Known bugs None. See FILE_SPLIT. FILE_SPLIT ---------- Command FILE_SPLIT Parameters template FILE/A Return template PATHPART, FILEPART Description Splits the given filename into seperate path and file parts. Parameters FILE/A The full filename to be split. Returns PATHPART The path (directory) part of the filename. FILEPART The file part of the filename. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following seperates the filename "Textures/Radar.itx" into seperate path and fileparts - the result is put in a pop up requester: FILE_SPLIT FILE "Textures/Radar.itx" STEM FILENAME. REQUEST_MESSAGE TEXT '"Path:'FILENAME.PATHPART, 'File:'FILENAME.FILEPART'"' The following seperates the filename "Ram:Radar.itx" into seperate path and fileparts - the result is put into the default settings of a file requester: FILE_SPLIT FILE "Ram:Radar.itx" STEM FILENAME. REQUEST_FILE PATHPART '"'FILENAME.PATHPART'"', FILE '"'FILENAME.PATHPART'"' Known bugs None. See FILE_JOIN. GUI_BLOCK --------- Command GUI_BLOCK Parameters template None. Return template None. Description Blocks any input to all of TextureStudio's windows. Stops the user from altering anything whilst a script is running. Note: Always remember to unblock the GUI once you have finished the script. Parameters None. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example blocks input to all the windows. GUI_BLOCK Known bugs None. See GUI_UNBLOCK. GUI_UNBLOCK ----------- Command GUI_UNBLOCK Parameters template None. Return template None. Description Unblocks all the windows after a GUI_BLOCK call. Allows the user to interact with the program again. Note: it is safe to call GUI_UNBLOCK, even if the windows are not currently blocked by GUI_BLOCK. Parameters None. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following unblocks all the windows. GUI_UNBLOCK Known bugs None. See GUI_BLOCK. LIGHT_GET --------- Command LIGHT_GET Parameters template None. Return template X_POS,Z_POS,INTENSITY/N,BACKLIGHT/N,POSITION,DISTANCE Description Gets the current settings about the light source. Parameters None. Returns X_POS,Z_POS These give the position of the light relative to the width of the scene visible. The floating point numbers are between -1 and 1. -1 corresponds to the extreme left and bottom. 1 corresponds to the extreme right and top. INTENSITY Gives the current light intensity from 0 to 200%. BACKLIGHT Gives the backlighting setting from 0 to 100%. POSITION This is a string containing the current setting of the `Position' slider in the light window. Can be `TOPLEFT', `TOP', `TOPRIGHT', `LEFT', `CENTRE', `RIGHT', `BOTTOMLEFT', `BOTTOM', `BOTTOMRIGHT' or `CUSTOM'. DISTANCE Gives the distance of the light source from the centre of the scene. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example gets the current light settings and puts them in a stem called `light.'. LIGHT_GET STEM 'light.' Known bugs None. See LIGHT_SET. See Light window. LIGHT_SET --------- Command LIGHT_SET Parameters template X_POS,Z_POS,INTENSITY/N,BACKLIGHT/N,POSITION,DISTANCE Return template None. Description Sets the current settings for the light source. Parameters X_POS,Z_POS These set the position of the light relative to the width of the scene visible. The floating point numbers must be between -1 and 1. -1 corresponds to the extreme left and bottom. 1 corresponds to the extreme right and top. INTENSITY Sets the current light intensity from 0 to 200%. BACKLIGHT Sets the backlighting setting from 0 to 100%. POSITION This is a string containing the current setting of the `Position' slider in the light window. Must be `TOPLEFT', `TOP', `TOPRIGHT', `LEFT', `CENTRE', `RIGHT', `BOTTOMLEFT', `BOTTOM', `BOTTOMRIGHT' or `CUSTOM'. DISTANCE Sets the distance of the light source from the centre of the scene. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example sets the light source to be in the extreme top right position. LIGHT_SET X_POS 1 Z_POS 1 POSITION "CUSTOM" Known bugs None. See LIGHT_GET. See Light window. OBJECT_GET ---------- Command OBJECT_GET Parameters template None. Return template OBJECT,RADIUS Description Gets the current object type and radius. Parameters None. Returns OBJECT Name of the type of object, can be `PLANE', `CYLINDER' or `SPHERE'. RADIUS A floating point number representing the radius of the object. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following gets the current object settings and places them into a stem called `object.'. OBJECT_GET STEM 'object.' Known bugs None. See OBJECT_SET. See Object window. OBJECT_SET ---------- Command OBJECT_SET Parameters template OBJECT,RADIUS Return template None. Description Sets the current object type and radius. Parameters OBJECT Name of the type of object, can be `PLANE', `CYLINDER' or `SPHERE'. RADIUS A floating point number representing the radius of the object. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following sets the current object to be a sphere of radius 30 units. OBJECT_SET "SPHERE" 30 Known bugs None. See OBJECT_GET. See Object window. OPEN ---- Command OPEN Parameters template FILE/A,FLUSH/S Return template None. Description This command opens a standard Imagine3 texture module. See Open texture. Parameters FILE/A This specifies the full filename of the texture module to be loaded. FLUSH/S This specifies whether any existing textures should be flushed out before loading in the specified file. Note that the `Flush textures on open' preference is ignored from ARexx, see Flush textures on open. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following opens a texture module called `Radar.itx' from the `Textures' drawer and closes all other textures. OPEN "Textures/Radar.itx" FLUSH The following loads the `Target.itx' file from the user's current texture directory. TEXTUREPATH_GET VAR 'texture_path' FILE_JOIN '"'texture_path'"' '"'Target.itx'"' VAR 'texture_file' OPEN '"'texture_file'"' Known bugs None. PARAMETER_GET ------------- Command PARAMETER_GET Parameters template INDEX/N/A Return template VALUE,TEXT Description This command is used to get a parameter value (floating point number) and text field (name of parameter). It gets the parameters from the currently selected texture. Parameters INDEX/N/A This is the index number of the parameter and must be from 0 to 15. Returns VALUE This is the floating point number associated with the given parameter INDEX. TEXT This is the text field of the parameter, e.g. `Colour Red'. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following gets the fifth (number 4) parameter from the current texture and returns the value and text in a stem called `param.'. PARAMETER_GET 4 STEM 'param.' The following example adds 1 onto the first parameter. PARAMETER_GET 0 STEM 'param.' new_value = param.value + 1 PARAMETER_SET 0 '"'new_value'"' Known bugs None. See PARAMETER_SET. See Parameters window. PARAMETER_SET ------------- Command PARAMETER_SET Parameters template INDEX/N/A,VALUE/A Return template None. Description Sets the given parameter to a given value for the currently selected texture. Parameters INDEX/N/A This is the index number of the parameter and must be from 0 to 15. VALUE/A This is a floating point number associated with the given parameter INDEX. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following sets the last parameter (number 15) to be 0 PARAMETER_SET 15 0 Known bugs None. See PARAMETER_GET. See Parameters window. PREFS_GET --------- Command PREFS_GET Parameters template None. Return template ALLOWTRANSOBJECT/N,CALCSURFNORMALS/N,FULLLIGHTCALCS/N, ANTIALIASING,FILEFORMAT,JPEG_QUALITY/N Description Gets the current preferences. Parameters None. Returns ALLOWTRANSOBJECT/N 0 for off, 1 for on. See Allow transparent object. CALCSURFNORMALS/N 0 for off, 1 for on. See Calculate surface normals. FULLLIGHTCALCS/N 0 for off, 1 for on. See Full light calculations. ANTIALIASING The anti-aliasing mode, can be `NONE', `LOW', `MEDIUM', `HIGH' or `VERYHIGH'. See Anti-aliasing. FILEFORMAT The current render file format. Can be `IFF-ILBM', `JPEG' or `TARGA'. See Render file format. JPEG_QUALITY The quality of the JPEG output. See JPEG options. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following returns the current preference settings and returns them in a stem called `pref.'. PREFS_GET STEM 'pref.' Known bugs None. See PREFS_SET. PREFS_SET --------- Command PREFS_SET Parameters template ALLOWTRANSOBJECT/N,CALCSURFNORMALS/N,FULLLIGHTCALCS/N, ANTIALIASING,FILEFORMAT,JPEG_QUALITY/N Return template None. Description Sets any given preference(s). Parameters ALLOWTRANSOBJECT/N 0 for off, 1 for on. See Allow transparent object. CALCSURFNORMALS/N 0 for off, 1 for on. See Calculate surface normals. FULLLIGHTCALCS/N 0 for off, 1 for on. See Full light calculations. ANTIALIASING Sets the anti-aliasing mode, can be `NONE', `LOW', `MEDIUM', `HIGH' or `VERYHIGH'. See Anti-aliasing. FILEFORMAT Sets the current render file format. Can be `IFF-ILBM', `JPEG' or `TARGA'. See Render file format. JPEG_QUALITY Sets the quality of the JPEG output. See JPEG options. Returns Nothing Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following sets the `Allow transparent object' preference off and sets the current render file format to be JPEG. PREFS_SET ALLOWTRANSOBJECT 0 FILEFORMAT "JPEG" Known bugs None. See PREFS_GET. RENDER ------ Command RENDER Parameters template TOBACK/S Return template None. Description Renders the current texture(s) to the HAM render screen. Parameters TOBACK/S If this is specified, the render screen is not brought to the front when rendering, it remains at the back. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following renders the current texture(s) to the HAM render screen in the background. RENDER TOBACK Known bugs None. See Render. RENDEROPTIONS_GET ----------------- Command RENDEROPTIONS_GET Parameters template None. Return template WIDTH/N,HEIGHT/N,MODEID/N,TOSCREEN/N,TOFILE/N,FILE Description Gets the current render options. Parameters None. Returns WIDTH/N The width of the render image in pixels. HEIGHT/N The height of the render image in pixels. MODEID/N A standard Amiga mode ID describing the screen mode. TOSCREEN/N Whether the image should be rendered to the screen. 0 for off, 1 for on. TOFILE/N Whether the image should be rendered to a file, given by FILE. 0 for off, 1 for on. FILE The filename of the render file. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following gets the current render options and returns them in a stem called `renderopts.' RENDEROPTIONS_GET STEM 'renderopts.' Known bugs None. See RENDEROPTIONS_SET. See Render options. RENDEROPTIONS_SET ----------------- Command RENDEROPTIONS_SET Parameters template WIDTH/N,HEIGHT/N,MODEID/N,TOSCREEN/N,TOFILE/N,FILE Return template None. Description Sets any of the current render options. Parameters WIDTH/N The width of the render image in pixels. HEIGHT/N The height of the render image in pixels. MODEID/N A standard Amiga mode ID describing the screen mode. TOSCREEN/N Whether the image should be rendered to the screen. 0 for off, 1 for on. TOFILE/N Whether the image should be rendered to a file, given by FILE. 0 for off, 1 for on. FILE The filename of the render file. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following sets the render width to be 320, the height to be 256 and the screen mode to be LowRes (mode ID = 0). RENDEROPTIONS_SET WIDTH 320 HEIGHT 256 MODEID 0 The following sets the render options so that TextureStudio will render to a file called `Renders/Explosion.JPG' in JPEG format and not to render to the screen, see PREFS_SET. RENDEROPTIONS_SET TOSCREEN 0 TOFILE 1 FILE "Renders/Explosion.JPG" PREFS_SET FILEFORMAT "JPEG" Known bugs None. See RENDEROPTIONS_GET. See Render options. RENDERPATH_GET -------------- Command RENDERPATH_GET Parameters template None. Return template PATH Description This returns the user's current directory (path) for render files. This command is useful used in conjunction with FILE_JOIN, see FILE_JOIN. Parameters None. Returns PATH The user's render path. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following gets the user's render path and returns it in a varaible called `pathpart' RENDERPATH_GET VAR 'pathpart' Known bugs None. RENDERSCREENPATH_GET -------------------- Command RENDERSCREENPATH_GET Parameters template None. Return template PATH Description This returns the user's current directory (path) for render screens. Parameters None. Returns PATH The user's render screen path. This command is useful used in conjunction with FILE_JOIN, see FILE_JOIN. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following gets the user's render screen path and returns it in a varaible called `pathpart' RENDERSCREENPATH_GET VAR 'pathpart' Known bugs None. RENDERSCREEN_CLOSE ------------------ Command RENDERSCREEN_CLOSE Parameters template None. Return template None. Description Closes the current render screen. Returns an error if there is no render screen currently open. ARexx equivelent to the `Close' gadget in the Infobar window. Parameters None. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following closes the current render screen. RENDERSCREEN_CLOSE Known bugs None. See Infobar window. RENDERSCREEN_SAVE ----------------- Command RENDERSCREEN_SAVE Parameters template FILE/A,FORCE/S Return template None. Description Saves the current render screen to the given FILE. Returns an error if there is no render screen currently open. ARexx equivelent to the `Save' gadget in the Infobar window. Parameters FILE/A Specifies the filename to save the HAM render screen as. FORCE/S If this is specified, files are automatically overwritten and no warning is given to the user. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example saves the current render screen to a file called `RenderScreens/Water.HAM8'. If the file already exists, it is overwritten. RENDERSCREEN_SAVE "RenderScreens/Water.HAM8" FORCE Known bugs None. See Infobar window. RENDERSCREEN_VIEW ----------------- Command RENDERSCREEN_VIEW Parameters template None. Return template None. Description Views the current render screen. Returns an error if there is no render screen currently open. ARexx equivelent to the `View' gadget in the Infobar window. Parameters None. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following closes the current render screen. RENDERSCREEN_CLOSE Known bugs None. See Infobar window. REQUEST_DIR ----------- Command REQUEST_DIR Parameters template PATHPART, TITLE Return template PATHPART Description Opens a directory requester, allowing the user to choose a directory name. The other TextureStudio windows are automatically blocked when the requester is opened and unblocked when the requester is closed. In common with all TextureStudio requesters, if the user presses `Cancel', an error message is returned. For the script to trap this error, global error checking must be turned off. See Error checking, for more information. Parameters PATHPART The default path name to put in the requester. TITLE The text for the title bar of the requester. Returns PATHPART The selected path from the requester. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason or the user cancelled requester, rc2 will contain a string describing the problem. Example The following puts up a directory requester, with the results being put in the DIRINFO. stem: REQUEST_DIR STEM DIRINFO. The following puts up a directory requester with a default directory of "T:", the result being printed in a message requester: REQUEST_DIR PATHPART "T:" STEM DIRINFO. REQUEST_MESSAGE TEXT '"You chose '||DIRINFO.PATHPART||'"' Known bugs None. REQUEST_FILE ------------ Command REQUEST_FILE Parameters template PATHPART, FILEPART, PATTERN, TITLE Return template FILE Description Opens a file requester, allowing the user to choose a filename. The other TextureStudio windows are automatically blocked when the requester is opened and unblocked when the requester is closed. In common with all TextureStudio requesters, if the user presses `Cancel', an error message is returned. For the script to trap this error, global error checking must be turned off. See Error checking, for more information. Parameters PATHPART The default path name to put in the requester. FILEPART The default filename to put in the requester. PATTERN An AmigaDos pattern matching pattern, will only show files in the requester which match the given pattern. By default, all files are shown. TITLE The text for the title bar of the requester. Returns FILE The selected filename from the requester, the filename consists of both the FILEPART and PATHPART parts. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason or the user cancelled requester, rc2 will contain a string describing the problem. Example The following puts up a file requester, with the results being put in the FILEINFO. stem: REQUEST_FILE STEM FILEINFO. The following puts up a file requester with the result being printed in a message requester. The default file is "Textures/Radar.itx": REQUEST_FILE PATHPART "Textures" FILEPART "Radar.itx", STEM FILEINFO. REQUEST_MESSAGE TEXT '"You chose '||FILEINFO.FILE||'"' The following will only show files with a ".itx" file extension: REQUEST_FILE PATTERN "#?.itx" Known bugs None. REQUEST_MESSAGE --------------- Command REQUEST_MESSAGE Parameters template TEXT/A, BUTTONTEXT, AUTOCANCEL/S, TITLE Return template NUMBER/N Description Opens a general purpose message requester. Simple messages can be presented to the user for them to "OK" them. OK / Cancel requesters can be built with this requester, as well a complex multiple choice requesters. When designing requesters, it is worth remembering the following rules: 1. The "Negative" response should be placed on the far right-hand button. For example, the `Cancel' button should be placed here. 2. The "Positive" response should be placed on the far left-hand button. For example, the `OK' button should be placed here. 3. Try to word your requesters to keep the positive and negative text as "OK" and "Cancel". Using options like "Go to it" and "Stop right here" doesn't make for a very intuitive interface. 4. Keep the request text short. The user shouldn't have to read a screen full of text to find out what to do next. 5. You should *NEVER* swap the "OK" and "Cancel" buttons around. 6. The last point is *VERY* important. The other TextureStudio windows are automatically blocked when the requester is opened and unblocked when the requester is closed. If the AUTOCANCEL option is used and the user presses `Cancel', an error message is returned. For the script to trap this error, global error checking must be turned off. See Error checking, for more information. Parameters TEXT/A The text to put into the requester. The text may contain multiple lines by including the `\n' characters in the string (see examples below). BUTTONTEXT The text for the buttons of the requester. The different buttons are seperated with a `|' character (i.e. BUTTONTEXT "OK|Cancel"). By default, only an "OK" button is placed in the requester. AUTOCANCEL/S By default REQUEST_MESSAGE simply returns the number of the button that the user selected. If the requester is of the OK / Cancel variety, specifying the AUTOCANCEL switch allows the requester to stop the script should the user press `Cancel'. TITLE The text for the title bar of the requester. Returns NUMBER The number of the selected button. If the requester has one button, NUMBER is set to 0. For more that one button, the right-most button sets NUMBER to 0, with the buttons being numbered from 1 upwards working left to right. For example, with a BUTTONTEXT of "OK|Save first|Cancel", "OK" would return 1, "Save first" would return 2 and "Cancel" would return 0. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. rc will also be set to 10 if the AUTOCANCEL option is used and the user selects `Cancel'. Example The following puts up a message requester: REQUEST_MESSAGE TEXT '"Operation finished"' The following puts up a OK / Cancel requester, stopping the script if the user selects `Cancel': REQUEST_MESSAGE TEXT '"Continue ?"' BUTTONTEXT "OK|Cancel", AUTOCANCEL The following shows a multiple choice requester, followed by a requester showing which option was chosen: REQUEST_MESSAGE TEXT '"Choose an option..."', BUTTONTEXT "First|Second|Third" REQUEST_MESSAGE TEXT '"You chose option '||RESULT||'"' The following shows a message requester with multiple lines of text using the `\n' characters: REQUEST_MESSAGE TEXT '"Top line\nMiddle line\nBottom line"' Known bugs None. REQUEST_MULTIFILE ----------------- Command REQUEST_MULTIFILE Parameters template PATHPART, FILEPART, PATTERN, TITLE Return template FILES/M Description Opens a file requester, allowing the user to choose multiple filenames. The other TextureStudio windows are automatically blocked when the requester is opened and unblocked when the requester is closed. In common with all TextureStudio requesters, if the user presses `Cancel', an error message is returned. For the script to trap this error, global error checking must be turned off. See Error checking, for more information. Parameters PATHPART The default path name to put in the requester. FILEPART The default filename to put in the requester. PATTERN An AmigaDos pattern matching pattern, will only show files in the requester which match the given pattern. By default, all files are shown. TITLE The text for the title bar of the requester. Returns FILES/M The selected filenames from the requester, the filenames consists of both the FILEPART and PATHPART parts. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason or the user cancelled requester, rc2 will contain a string describing the problem. rc will also be set to 10 if no files are chosen. Example The following puts up a multifile requester, with the results being put in the MULTIFILEINFO. stem: REQUEST_MULTIFILE STEM MULTIFILEINFO. The following puts up a multifile requester, with a default path of "Textures" and loops through all the selected files by putting them in message requesters: REQUEST_MULTIFILE PATHPART "Textures" STEM MULTIFILENFO. do l = 0 to (MULTIFILENFO.FILES.COUNT - 1) REQUEST_MESSAGE TEXT '"'MULTIFILENFO.FILES.l'"', BUTTONTEXT '"More...|Cancel"' AUTOCANCEL end Known bugs If no file is chosen, the command returns a "user cancelled" error. This is normal. SCREEN_BACK ----------- Command SCREEN_BACK Parameters template None. Return template None. Description This sends TextureStudio's main screen to the back. Parameters None. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following sends TextureStudio's screen to the back. SCREEN_BACK Known bugs None. See SCREEN_FRONT. SCREEN_FRONT ------------ Command SCREEN_FRONT Parameters template None. Return template None. Description This brings TextureStudio's main screen to the front. Parameters None. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following brings TextureStudio's screen to the front. SCREEN_FRONT Known bugs None. See SCREEN_BACK. TEXTUREPATH_GET --------------- Command TEXTUREPATH_GET Parameters template None. Return template PATH Description This returns the user's current directory (path) for textures. This command is useful used in conjunction with FILE_JOIN, see FILE_JOIN. Parameters None. Returns PATH The user's render path. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following gets the user's texture path and returns it in a varaible called `pathpart' TEXTUREPATH_GET VAR 'pathpart' Known bugs None. TEXTURES_GET ------------ Command TEXTURES_GET Parameters template None. Return template NAME/M Description This gets the names of all the currently open textures. Parameters None. Returns NAME/M The names of all the textures. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example gets the names of all the open textures and displays each one in turn with a requester. TEXTURES_GET STEM 'texture.' do l = 0 to (texture.name.count - 1) REQUEST_MESSAGE TEXT '"'texture.name.l'"', BUTTONTEXT '"More...|Cancel"' AUTOCANCEL end Known bugs None. TEXTURE_SELECT -------------- Command TEXTURE_SELECT Parameters template NAME/A Return template None. Description Selects a texture to make it the current texture. Parameters NAME/A This is the name of texture. You need only supply as many characters in the name to distinguish it from other textures. For example, if you wanted to select the `GasGiant' texture, you need only give a NAME of `GasG'. The name is case insensitive. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example selects the `Radar' texture. TEXTURE_SELECT "Radar" Known bugs None. VIEW_GET -------- Command VIEW_GET Parameters template None. Return template VISIBLEWIDTH,XYASPECT Description Gets the current view settings. Parameters None. Returns VISIBLEWIDTH The current visible width as a floating point number. XYASPECT The current X/Y aspect ratio as a floating point number. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example gets the current view settings and returns them in a variable called `view.' VIEW_GET STEM 'view.' Known bugs None. See VIEW_SET. See View window. VIEW_SET -------- Command VIEW_GET Parameters template VISIBLEWIDTH,XYASPECT Return template None. Description Sets the current view settings. Parameters VISIBLEWIDTH The current visible width as a floating point number. XYASPECT The current X/Y aspect ratio as a floating point number. Returns Nothing. Errors rc = 0 if the operation was successful. rc = 10 if the operation failed for any reason, rc2 will contain a string describing the problem. Example The following example sets the current visible width to be 50 units and the aspect ratio to be 1. VIEW_SET VISIBLEWIDTH 50 XYASPECT 1 Known bugs None. See VIEW_GET. See View window. Tooltypes ********* The tooltypes for TextureStudio set some important preferences for the program such as the name of the public screen and ARexx port. The tootypes apply when starting TextureStudio from the Workbench by double clicking on it's icon or when starting it form the shell and supplying some arguments, see Starting TextureStudio. PUBSCREEN ========= Name PUBSCREEN Default TEXTURESTUDIO Description This sets the public screen name for the screen that TextureStudio opens. This name must be unique, otherwise the screen will not open. PORTNAME ======== Name PORTNAME Default TEXTURESTUDIO Description The name of the ARexx portname used by the program. If a portname by that name already exists, the name is incremented until a free portname is found. For example, if `TEXTURESTUDIO' was already in use, the following sequence of names would be tried: `TEXTURESTUDIO.1', `TEXTURESTUDIO.2', `TEXTURESTUDIO.3' ... When choosing an ARexx portname, try to keep it fairly short. KEYFILE ======= Name KEYFILE Default TextureStudio.keyfile Description The filename of the keyfile to use to unlock TextureStudio to use all 16 parameters. Keyfiles are obtaining by registering (see How to register). PREFSFILE ========= Name PREFSFILE Default TextureStudio.prefs Description The sets the filename of the preferences file that TextureStudio uses to set up it's defaults on startup. If TextureStudio cannot find the filename given, the settings will be reset to the built in defaults. Known bugs ********** * It seems that some of the textures supplied with Imagine3 that were originally with Imagine2; Bricks and Dots don't work correctly. The bricks texture doesn't affect the object at all and the Dots texture only creates one-quarter of complete circle for each dot. Other textures like Disturbed, Grid, Waves and Wood seem to work fine. Note: TextureStudio will not work with textures taken directly from Imagine2, it only supports Imagine3 textures. * When rendering to a transparent cylinder or sphere, the `other side' of the object cannot be seen through the front surface. This gives the impression of a hemi-sphere and not a complete sphere. This is something that may get fixed in the future, see Future additions. Common questions **************** If you have any questions about TextureStudio, make sure that they haven't already been answered below: Common question 1 ================= "Why doesn't TextureStudio support Imagine2 textures?" The Imagine2 texture format differs to the Imagine3 format and the details about the Imagine2 format were not released by Impulse. Common question 2 ================= "Why isn't there a non-FPU version?" All but the very basic textures supplied with Imagine3 require an FPU. The authors *********** TextureStudio was written by Graham Dean and Andy Dean. Queries and orders (see How to register) should be sent to Graham at: Graham Dean, 14 Fielding Avenue, Poynton, Cheshire. SK12 1YX ENGLAND Andy can be reached for queries (no orders) via Internet Email at: adean@eleceng.ucl.ac.uk The rate at which TextureStudio progresses depends on a few things: 1. You. If you like and use the program, please register it. If you like the program but think it is missing something that isn't already in our future additions list (see Future additions) *let us know!*. 2. Other work. Graham is studying `A' levels and Andy is doing a PhD and this work will take priority (sad, but true). If you find a bug in TextureStudio that is not covered in the `Known bugs' list (see Known bugs), inform the authors at the above addresses. Be sure to include as much information as possible, the version of TextureStudio being used, a description of the Amiga system you are running (model, amount of RAM, Workbench version, any expansion cards). How to register *************** To receive the full version of TextureStudio, send 10 pounds sterling (20 US dollars overseas) to: Graham Dean, 14 Fielding Avenue, Poynton, Cheshire. SK12 1YX ENGLAND We will accept the following methods of payment: * 10UK pounds cash. * A 10UK pounds cheque, drawn on a UK bank. * A 10UK pounds postal order, purchased in the UK. * 20US dollars cash. * International money order. We *don't* accept any foreign cheques drawn on non-UK banks and we *don't* accept any foreign postal orders. We also cannot accept Eurocheques for any value (USdollars or UKpounds). Note: Make sure that when sending cash, it is well wrapped in the envelope. In return you will receive the latest version of TextureStudio, along with a personal keyfile to unlock the package. Each keyfile is unique to the registered user, please do not distribute the keyfile to others as it can be traced back to you. Allow a resonable time to allow cheque clearance, the processing of the order, etc... Upgrades will be offered to registered users free of charge. As we are operating a keyfile concept, upgrades can be obtained by getting the latest version from the Internet, Aminet, BBS's, PD houses etc... If your local provider doesn't have the latest version, pester them until they get it! Upgrades will not be given by contacting the authors directly, unless there is a very good reason for it (we're sorry, but we don't have the resources to deal with lots of registered users all wanting upgrades at the same time!). The version number of TextureStudio (see About) is to be interpreted as: version.revision.subrevision The `version' shows the main version of the program, `revision' will be increased as small additions and improvements are made to the program. The `subrevision' value is incremented with bug fixes. All the values are simple decimal, not floating point, so version 1.9.0 would be followed by version 1.10.0. New versions will be distributed with every change in revision number, bug fixes are likely to be distributed as "patches" (more details to follow). Credits ******* The authors would like to thank: * Commodore-Amiga. * Our parents for their support (especially our mum for also helping with the posting and packing!!!). * Impulse for Imagine3 and its wonderful textures. * SAS Institute, for the `SAS/C' C compiler. * Ian OConner, for `The Designer' - used to do all the GUI windows design. * Michael Balzer, for `ARexxBox' - used to implement the ARexx port. * Jonathan Forbes, for `LX' - used to decompress the .lha files in the distribution. * All the public domain / freeware / shareware authors, for loads of great software. * The Independant JPEG Group, for their essential JPEG code and information. * All those involved with the excellent TeX and `TeXinfo' packages. TextureStudio has been tested on: - A1200, Workbench 3.0, 2Mbyte CHIP RAM, 4MByte FAST RAM, Power PC1204 expansion card, 68882 FPU, 270Mbyte IDE hard drive. - A1200, Workbench 3.0, 2Mbyte CHIP RAM, 8MByte FAST RAM, Power Viper 030 expansion card with MMU, 68882 FPU, 270Mbyte IDE hard drive. - A4000/EC030, Workbench 3.0, 2Mbyte CHIP RAM, 8MByte FAST RAM, 68882 FPU, 130Mbyte + 420Mbyte IDE hard drives. TextureStudio shows no problems with either the `Enforcer' or `Mungwall' debugging tools. Future additions **************** The following features may be added to future versions, they are listed roughly in order. * Proper transparent objects, see Known bugs. * Animation control from the GUI. * Better multiple pass render, i.e. blocky redraw. * Printing the texture's name onto the HAM render screen for identification purposes. Any ideas? Example textures **************** The following are descriptions of the example textures included in this package. The textures are freely distributable so feel free to use as you wish. Blades texture ============== Type Colour, filter Description This texture creates circular blades similar to propeller or fan blades. Parameters The parameters can alter the number of blades, the blade radius and amount of space the blades occupy. The blades can be made to fade away with the `fade adjust' parameter. The colour and filter of the blades can be adjusted. For example if you set the object filter to be 255,255,255 and the blade filter to be 0,0,0, the object rendered will be totally transparent except for the blades themselves. This texture can be animated to simulate spinning blades by adjusting the `Sweep angle' parameter. Axis The axis position sets the centre of the blades. The axis sizes are ignored. Sample object Plane or disk with default settings. Radar texture ============= Type Colour Description This texture creates are radar screen similar to that on a submarine or airplane. Parameters The radar image consists of a grid made of 2 lines, one horizontal, one vertical, concentric circles and the radar sweep itself. The width of the grid lines and concentric circles can be adjusted with the `Grid width' and `Circle width' parameters. The colour of the grid and radar sweep can be adjusted. The radar sweep fades to the object colour so it is possible to overlay the radar texture onto a brush map with Imagine. The `Fade adjust' parameter alters how much the radar sweep fades away. This texture can be animated to simulate a sweeping radar by adjusting the `Sweep angle' parameter. Axis The axis position sets the centre of the radar. The axis sizes are ignored. Sample object Plane or disk with default settings. Target texture ============== Type Colour Description This texture creates overlayed concentric filled circles which can be used to simulate an archer's target or the RAF markings. Parameters The fourth circle is layered on top of the third circle which is layered on top of the second circle which is layered on top of the first circle. Therefore the first circle has the lowest priority. Any of the circle's radii may be set to 0 to remove it. The colours of each circle can be adjusted. Note: This texture is clipped by the y axis, this allows multiple copies of the texture to be applied to an object. Axis The axis position marks the centre of the target. The y-axis size alters the depth at which the texture affects. Sample object Plane or disk with default settings. WarningStripes texture ====================== Type Colour Description The texture was designed for creating the seen-too-many-times-before warning stripes on spaceships etc. The texture consists of a rectangle with diagonal stripes of alternating colours. The rectangle is set by the bounding box of the axis and so multiple copies of this texture can be applied to one object. Parameters The width of the stripes can be adjusted as can the amount of each colour with the `Fraction on' parameter. The slope adj parameter adjusts the slope of the stripes, a setting of -1 gives a 45 degree slope to the right, a setting of 1 gives a 45 degree slope to the left and a setting of 0 gives horizontal stripes. The colour of each stripe can be adjusted. Axis The axis size and position set the bounding box for the texture. Sample object Plane with default settings. ImageStudio *********** The authors of TextureStudio have also written a shareware image processing package called "ImageStudio". ImageStudio is written for the casual graphics user who wishes to manipulate images on a modest Amiga system. ImageStudio includes the following features: General: * Full 24-bit image buffers, with optimizations for colour-mapped (palette based) images. * Up to 100 levels of undo / redo. * User configurable virtual memory. * Fully font sensitive, style guide complient, user interface. * Fully featured, easy to use, ARexx interface. * Internal / external viewers (external for third party 24-bit graphics cards). * Loading / saving / manipulating of AGA image formats (e.g. 256 colours, HAM8) on non-AGA machines. * Max image size of 32000 x 32000 (limited to 250 x 250 in the unregistered version). * Runs on all Workbench 2.04+ Amiga's - utilises AGA chipset if available. * Online AmigaGuide help, as well as ASCII, TeX `.dvi' and PostScript documentation. * Requires no third party libraries or utilities. File formats: * IFF-ILBM formats (Standard palette based, HAM6, HAM8, extra halfbright, ILBM24), BMP, EPS, GIF (conforming to GIF87a), JPEG (conforming to JFIF standard), PCX, Targa, any installed Amiga datatype (with Workbench 2.1+) Operations: * Brightness, Contrast, Gamma, Convolution (includes user definable), Dynamic range expansion, FlipX, FlipY, RollX, RollY, Negative, Greyscale, Highlight, Shadow, Random, Pixelize, Remove isolated pixels, Crop, Scale, Colour reduction (with many dithers), Palette manipulation ImageStudio costs 10UK pounds or 20US dollars and is available by writing to the authors at the same address as TextureStudio (see How to register). A demo version, limited to loading images of upto 250x250 pixels, is available from most PD libraries and available by anonymous ftp from Aminet (gfx/conv directory). ImageStudio has recently won the Amiga Shopper 1995 reader award for `Best PD / Shareware Utiltity'. Other reviews have said: "This program is superb." Amiga Pro, Larry Hickmott, December '94 "This is a real prize program. ... Registration is only 10UK pounds, a sound investment if you ask me... 96%" Amiga User International, December '94 "Perhaps the most impressive feature is the option to use a hard disk as virtual memory ... a feature that would be welcome in many commercial offerings." Amiga Computing, December '94 "It's a promising package... 88%" Amiga Format, November '94 "ImageStudio is an impressive program - all the more considering this is the first revision... 90%" Amiga Shopper, December '94 "It is impossible to choose between ImageStudio and Blackboard, [Blackboard] has better effects, but [ImageStudio] has better overall handling... 89%" C.U.Amiga, December '94 "This is a very stable and useful program with features which are worth a lot more that the asking price. ... I urge you to contribute your shareware fee as soon as possible to get the most from this excellent program." Amiga Pro, Phil South, December '94 "Probably the most incredible thing about ImageStudio is that it is as solid as a rock." JAM, December '94 "It's been a long time since I've seen a shareware program as good as ImageStudio." EM, December '94